feat: FDv2 Cache Initializer by kinyoklion · Pull Request #1147 · launchdarkly/js-core

kinyoklion · 2026-03-03T23:19:37Z

Note

Medium Risk
Touches persistence and FDv2 data-source plumbing by adding new cached-data paths and new storage keys, which could affect startup behavior and cache correctness across contexts. Changes are well-covered by new unit tests but still impact core flag loading/poll timing logic.

Overview
Adds an FDv2 CacheInitializer that loads cached flag evaluations from persistent storage (including legacy-key fallback), returns them as a changeSet without a selector, and supports early shutdown via close().

Introduces cache “freshness” metadata: FlagPersistence now writes/evicts {contextKey}_freshness records (timestamp + context hash), readFreshness validates them, and FDv2SourceResult.changeSet can carry an optional freshness value; also adds calculatePollDelay to derive the next poll delay from freshness.

Refactors/expands tests to cover the new cache initializer, freshness persistence/eviction, and updates existing storage tests for the additional storage writes; shared test helpers are centralized in flagManagerTestHelpers.ts.

^{Written by Cursor Bugbot for commit ccae06f. This will update automatically on new commits. Configure here.}

github-actions · 2026-03-03T23:21:09Z

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25566 bytes
Compressed size limit: 26000
Uncompressed size: 125383 bytes

github-actions · 2026-03-03T23:21:25Z

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 172130 bytes
Compressed size limit: 200000
Uncompressed size: 800872 bytes

github-actions · 2026-03-03T23:21:27Z

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 24212 bytes
Compressed size limit: 25000
Uncompressed size: 83755 bytes

github-actions · 2026-03-03T23:21:35Z

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 21281 bytes
Compressed size limit: 24000
Uncompressed size: 110213 bytes

kinyoklion · 2026-03-04T22:34:05Z

      }
    },
-    initCached(context: Context, newFlags: { [key: string]: ItemDescriptor }) {
+    initCached(context: Context, newFlags: { [key: string]: ItemDescriptor }, _freshness?: number) {


We aren't doing anything with this yet, but likely we will want to expose it from the flag manager.

kinyoklion · 2026-03-04T23:27:18Z

bugbot review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

kinyoklion · 2026-03-04T23:46:56Z

@@ -121,16 +136,22 @@ export default class FlagPersistence {
  }

  private async _storeCache(context: Context): Promise<void> {


With this change we start recording freshness even in the FDv1 path.

kinyoklion · 2026-03-04T23:47:18Z

@@ -56,47 +63,55 @@ export default class FlagPersistence {
   * {@link FlagUpdater} this {@link FlagPersistence} was constructed with.
   */
  async loadCached(context: Context): Promise<boolean> {


Once we remove V1 support this loading path will be removed.

🤖 I have created a release *beep* *boop* --- <details><summary>browser: 0.1.12</summary> ## [0.1.12](browser-v0.1.11...browser-v0.1.12) (2026-03-16) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-client-sdk bumped from 4.3.1 to 4.4.0 </details> <details><summary>browser-telemetry: 1.0.28</summary> ## [1.0.28](browser-telemetry-v1.0.27...browser-telemetry-v1.0.28) (2026-03-16) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/js-client-sdk bumped from 4.3.1 to 4.4.0 </details> <details><summary>jest: 1.0.7</summary> ## [1.0.7](jest-v1.0.6...jest-v1.0.7) (2026-03-16) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/react-native-client-sdk bumped from ~10.14.1 to ~10.15.0 </details> <details><summary>js-client-sdk: 4.4.0</summary> ## [4.4.0](js-client-sdk-v4.3.1...js-client-sdk-v4.4.0) (2026-03-16) ### Features * Add experimental FDv2 configuration (unused) ([#1169](#1169)) ([c7130cc](c7130cc)) * create @launchdarkly/js-contract-test-utils package ([#1163](#1163)) ([2de5c27](2de5c27)) ### Bug Fixes * Allow 0 status code to be handled by the streaming error filter. ([d96b46b](d96b46b)) * Improve error handling for FDv2 streaming ([d96b46b](d96b46b)) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-client-sdk-common bumped from 1.21.0 to 1.22.0 </details> <details><summary>js-client-sdk-common: 1.22.0</summary> ## [1.22.0](js-client-sdk-common-v1.21.0...js-client-sdk-common-v1.22.0) (2026-03-16) ### Features * Add experimental FDv2 configuration (unused) ([#1169](#1169)) ([c7130cc](c7130cc)) * Add explicit disableCache setting. ([6be89dd](6be89dd)) * Add FDv1 polling synchronizer for FDv2 fallback (SDK-1923) ([#1159](#1159)) ([498216a](498216a)) * Add mode resolution table for FDv2. ([#1146](#1146)) ([ab2436d](ab2436d)) * FDv2 Cache Initializer ([#1147](#1147)) ([7d6299f](7d6299f)) ### Bug Fixes * Allow 0 status code to be handled by the streaming error filter. ([d96b46b](d96b46b)) * Fix the calculation of the basis parameter for FDv2 streaming. (Does not affect FDv1). ([#1165](#1165)) ([bbdd6c6](bbdd6c6)) * Improve error handling for FDv2 streaming ([d96b46b](d96b46b)) * Max cached context enforcement wasn't working for 0. ([6be89dd](6be89dd)) * rename FDv2 object kind from `flagEval` to `flag-eval` ([#1185](#1185)) ([cd4b119](cd4b119)) </details> <details><summary>react-native-client-sdk: 10.15.0</summary> ## [10.15.0](react-native-client-sdk-v10.14.1...react-native-client-sdk-v10.15.0) (2026-03-16) ### Features * Add experimental FDv2 configuration (unused) ([#1169](#1169)) ([c7130cc](c7130cc)) * create @launchdarkly/js-contract-test-utils package ([#1163](#1163)) ([2de5c27](2de5c27)) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-client-sdk-common bumped from 1.21.0 to 1.22.0 </details> <details><summary>server-sdk-ai: 0.16.6</summary> ## [0.16.6](server-sdk-ai-v0.16.5...server-sdk-ai-v0.16.6) (2026-03-16) ### Bug Fixes * Make defaultValue optional with a disabled default ([#1144](#1144)) ([e46769b](e46769b)) </details> <details><summary>server-sdk-ai-langchain: 0.5.2</summary> ## [0.5.2](server-sdk-ai-langchain-v0.5.1...server-sdk-ai-langchain-v0.5.2) (2026-03-16) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/server-sdk-ai bumped from ^0.16.5 to ^0.16.6 * peerDependencies * @launchdarkly/server-sdk-ai bumped from ^0.15.0 || ^0.16.0 to ^0.16.6 </details> <details><summary>server-sdk-ai-openai: 0.5.2</summary> ## [0.5.2](server-sdk-ai-openai-v0.5.1...server-sdk-ai-openai-v0.5.2) (2026-03-16) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/server-sdk-ai bumped from ^0.16.5 to ^0.16.6 * peerDependencies * @launchdarkly/server-sdk-ai bumped from ^0.15.0 || ^0.16.0 to ^0.16.6 </details> <details><summary>server-sdk-ai-vercel: 0.5.2</summary> ## [0.5.2](server-sdk-ai-vercel-v0.5.1...server-sdk-ai-vercel-v0.5.2) (2026-03-16) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/server-sdk-ai bumped from ^0.16.5 to ^0.16.6 * peerDependencies * @launchdarkly/server-sdk-ai bumped from ^0.15.0 || ^0.16.0 to ^0.16.6 </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).  --- > [!NOTE] > **Low Risk** > Primarily automated release/version bumps and changelog updates across multiple packages; no functional code changes beyond embedded SDK version constants and dependency bumps. > > **Overview** > Publishes a new release across the monorepo by bumping versions in `.release-please-manifest.json`, updating package `CHANGELOG.md`s, and syncing `package.json` dependency ranges. > > Notable bumps include `@launchdarkly/js-client-sdk` to `4.4.0` (and `@launchdarkly/js-client-sdk-common` to `1.22.0`), `@launchdarkly/react-native-client-sdk` to `10.15.0`, `@launchdarkly/server-sdk-ai` to `0.16.6`, and corresponding provider/aggregator packages (`server-sdk-ai-*`, `@launchdarkly/browser`, `browser-telemetry`, `@launchdarkly/jest`). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit a6d9634. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>  Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

feat: FDv2 Cache Initializer

00c25df

kinyoklion added 4 commits March 3, 2026 15:24

Freshness record evictions.

2e0a662

Freshness accounts for all attributes of contexts.

35a20b7

Integrated into persistence.

e990e55

Refine compatibility story.

13cf993

kinyoklion commented Mar 4, 2026

View reviewed changes

kinyoklion added 4 commits March 4, 2026 14:42

Handle errors hashing context.

5a16d8d

Plumb cache freshness.

0915817

Common cache loading

30c365a

Merge branch 'main' into rlamb/sdk-1922/cache-initializer

41e6d18

cursor Bot reviewed Mar 4, 2026

View reviewed changes

kinyoklion commented Mar 4, 2026

View reviewed changes

Protect from clock drift.

417412d

kinyoklion marked this pull request as ready for review March 4, 2026 23:52

kinyoklion requested a review from a team as a code owner March 4, 2026 23:52

joker23 reviewed Mar 5, 2026

View reviewed changes

Comment thread packages/shared/sdk-client/src/flag-manager/FlagPersistence.ts

Restore logging.

72ed8d8

This comment was marked as resolved.

Sign in to view

PR feedback

cd405a4

This comment was marked as resolved.

Sign in to view

PR feedback

e044703

kinyoklion requested a review from joker23 March 5, 2026 17:34

This comment was marked as resolved.

Sign in to view

Re-order freshness write.

ccae06f

joker23 approved these changes Mar 5, 2026

View reviewed changes

kinyoklion merged commit 7d6299f into main Mar 5, 2026
42 checks passed

kinyoklion deleted the rlamb/sdk-1922/cache-initializer branch March 5, 2026 21:47

github-actions Bot mentioned this pull request Mar 5, 2026

chore: release main #1154

Merged

		@@ -121,16 +136,22 @@ export default class FlagPersistence {
		}

		private async _storeCache(context: Context): Promise<void> {

Conversation

kinyoklion commented Mar 3, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 3, 2026

Uh oh!

github-actions Bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kinyoklion Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

kinyoklion commented Mar 4, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

kinyoklion Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

kinyoklion Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kinyoklion commented Mar 3, 2026 •

edited by cursor Bot

Loading

github-actions Bot commented Mar 3, 2026 •

edited

Loading

github-actions Bot commented Mar 3, 2026 •

edited

Loading

github-actions Bot commented Mar 3, 2026 •

edited

Loading